package com.founder.devwork.persistence.gateway.gitlab;

import com.founder.devwork.persistence.gateway.gitlab.datasource.GitDataSource;
import com.founder.devwork.persistence.gateway.gitlab.dto.CommitDTO;
import com.founder.devwork.persistence.gateway.gitlab.dto.CommitPkDTO;
import com.founder.devwork.persistence.gateway.gitlab.dto.RepoDTO;
import com.founder.devwork.persistence.gateway.gitlab.dto.UserDTO;
import java.util.List;
import java.util.Set;

/**
 * 接口：GitGateway
 * <p>目的：定义统一 API 方法，封装 GitLab 调用逻辑。所有方法返回 DTO 或 List<DTO>，抛出异常时统一处理。
 * <p>设计原则：作为 Facade（门面），统一暴露 API，隐藏底层 HTTP 调用细节。支持注入 DataSource 以切换 GitLab 实例。
 * <p>参考：git-api-design.md 中的 Gateway 设计。
 */
public interface GitGateway {
    /**
     * 获取所有仓库，分页。
     * @param page 页码
     * @param perPage 每页数量
     * @return 仓库 DTO 列表
     */
    List<RepoDTO> getAllRepos(int page, int perPage);

    /**
     * 获取指定仓库。
     * @param repoId 仓库 ID 或路径
     * @return 仓库 DTO
     */
    RepoDTO getRepoById(Long repoId);

    /**
     * 获取所有用户，分页。
     * @param page 页码
     * @param perPage 每页数量
     * @return 用户 DTO 列表
     */
    List<UserDTO> getAllUsers(int page, int perPage);

    /**
     * 获取指定用户。
     * @param userId 用户 ID
     * @return 用户 DTO
     */
    UserDTO getUserById(Long userId);

    /**
     * 获取指定仓库的所有分支。
     * @param repoId 仓库 ID
     * @return 分支名称列表
     */
    List<String> getBranches(Long repoId);

    /**
     * 设置数据源，用于运行时切换 GitLab 实例。
     * @param dataSource GitDataSource 实例
     */
    void setDataSource(GitDataSource dataSource);

    /**
     * 获取指定仓库和分支的提交唯一ID，分页，支持时间范围。
     *
     * @param repoId 仓库 ID
     * @param branch 分支名称
     * @param sinceDate 开始日期
     * @param untilDate 结束日期
     * @param page 页码
     * @param perPage 每页数量
     *
     * @return 提交唯一ID DTO 列表, sha 不重复
     */
    Set<CommitPkDTO> getCommitsPk(Long repoId, String branch, String sinceDate, String untilDate, int page, int perPage);

    /**
     * 获取指定仓库和分支的提交详情。
     * @param pk 提交唯一ID DTO
     * @return 提交详情 DTO
     */
    CommitDTO getCommitByPk(CommitPkDTO pk);
}
